NewString
returns handle leading to a Pascal-style string
NewString allocates the minimum heap-storage to hold a Pascal-style
string, and returns a handle to that storage.
theString is the address of a Pascal string. It may be up to 255 bytes long.
The string's length byte specifies the amount of memory to be
allocated.
Returns: a StringHandle leading to the storage allocated.
Notes: If you intend to manipulate the string (e.g., copy a larger one to it later),
you may wish to allocate a maximum-length 255-byte string or use
SetHandleSize to expand the handle's storage area to the 256-byte max.
For "long-term" storage of strings, the heap is better than a fixed- length
buffer since heap objects can be compacted when a memory shortage occurs.
For C-style strings, you are probably best off creating generic heap
objects; e.g.:
Handle cSt rHandle;
char *cStr;
/* -------- to allocate storage, copy to the heap, and obtain a handle */